This file is a special BLACK MAGIC Hypertext document. To read me
obtain MAGREAD.ARC from a local bulletin board, free of charge, or
send $7 to:
NTERGAID
2490 BLACK ROCK TPK SUITE 337
FAIRFIELD, CT 06840
to receive, a disk copy of MAGREAD.ARC.
You'll also get some of the latest documents written with BLACK MAGIC.
Thank You
NTERGAID, Inc.
î╪6+]'Ä╪X├εå─BεJ├PR║ εB O //////////////////// F
F //////////////////// F
F ////////////////////" O O ////////////////////B O O ////////////////////J O
F ////////////////////N 2
2 ////////////////////O 2
2 ////////////////////Q F
F ////////////////////S 2
2 ////////////////////T 2
2 ////////////////////U F
F ////////////////////W F
F ////////////////////\ N O ////////////////////] N M ////////////////////_ N O ////////////////////` N M ////////////////////b 2
2 ////////////////////c O O ////////////////////z 2
2 ////////////////////{ N O ////////////////////| N M ////////////////////é F
F ////////////////////à F
F ////////////////////ê N O ////////////////////ë N M ////////////////////É O O ////////////////////ö N O ////////////////////ò N M ////////////////////Ü N O ////////////////////¢ N M ////////////////////á * O O ////////////////////╩ O
F ////////////////////▄ N O ////////////////////▌ N M ////////////////////µ F
F ////////////////////δ 2
2 ////////////////////∞ 2
2 ////////////////////ε O
F ////////////////////÷ O O //////////////////// F
F //////////////////// 2
2A Named Window /////
F
F //////////////////// 2
2 //////////////////// //////////////////// //////////////////// //////////////////// //////////////////// N N //////////////////// //////////////////// //////////////////// //////////////////// //////////////////// //////////////////// N N //////////////////// //////////////////// |U äU start wri ; . |U äU start wri ; . |U äU start wri ; . 7 1┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ - HELP │ │ ' . NEXT │ │ / ,PREVIOUS│ │ 0 CONTENTS│ │ 1 QUIT │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ Chapter 8. Limitations Creating Hypertext Links ... File Links Hypertext Reports The process of creating hypertext links is relatively straight forward however
it does require explanation. That is the purpose of this chapter, to explain
each type of link and how to create it. In General ... Creating hypertext can be broken down into a series of simple Steps. The following keys are used to designate hypertext links. Key Combination Function Symbol <F2> Reference Link Green Triangle <Alt> <F3> ! Replacement Link Pink Rectangle <Shift> <F3> ( Note Link Yellow Diamond <Ctrl> <F4> DOS Link Red Floppy Disk <F2> Mark Graphic Circle w/ 'X' To The Reader: 1. First define the block of text that is to be hypertext.
(the Link Originator) 2. Choose the form of hypertext that it is to be and press
that key combination. 3. Type the text that the block is to be linked to (the Link End). Alternatively existing text can be used
(point mode) for Reference links. 4. Back out of the link, and you're done. As Note Links are the simplest form of link, you may wish to
begin your studies of how to create links with the 'Note
Link' Link above. /Reference Link Point Mode Summary Reference Links are used to "jump" the reader to another point in the document
when activated. The point that the user is taken to can be text, graphics, or
any mixture of the two. The user can even designate hypertext links (all
kinds) in the area that the user is taken to, thus infinitely treeing off
of the first hypertext link. The symbol for a Reference Link is a green
triangle surrounding the Link Originator. About Reference Links Creating a reference link is more involved than a creating a note or
replacement link, because you must have some idea of where you are in the
document's "Structure". One item to consider when creating reference links is they can be made in two
ways: Linking to New Text Linking to Existing Text Creation of Reference Links To start creating a reference link, you must first define the block that is
to be become hypertext. Next, by pressing <F3>, the block will be defined as a
reference link. The user is then queried with the following: "Is This Going To Point To New Text ? (Y/N)" This means, do you wish the Reference Link you are making to go to text that
already exists or is the Link going to text that is yet to be typed. Creation Con't - New Text If you answer "Y" then the screen will clear and provide you with a blank
screen to type the text on. After the text has been typed, bypressing <Esc>
the following prompt will appear: The Reference Link's End Points have not been defined. Do you wish to link the entire block of Text Just Typed? (Y/N) What this means, is that the reference link can be defined in two ways. Answering "Y" Pressing "N" Upon returning from completion of a link, there are some changes evident on
the screen. Visual Changes Functional Changes Creation Con't - Point Mode Point mode is entered into by answering the following prompt after a reference
link has been defined. Is this going to point to new text (Y/N) ? If this prompt is answered with a "Y" then a blank screen appears for typing
and the material for the reference link can be entered as above. However if "N" is answered to this prompt Black Magic goes into Point Mode. In
Point Mode Black Magic puts hypertext markers around the block that was
defined as hypertext and displays the words " Point Mode " on the command
line. In this mode Black Magic allows you to step through the document using the
movement keys and <F1> to the specific location where the Reference link is to
be linked to. Once at the correct location the text that it is to be linked
to is marked as a block and <Esc> is pressed. This traverses the link
backwards to the link originator. When activated this link will take you to
the text that was marked as a block in point mode. Overall Point Mode
provides an easy way to create Reference links using existing text. Reference Link Summary Creating a Reference Link is done in the following manner. 1. Mark the block of text that is to be hypertext. 2. Press <F3>. 3. Answer the "New text" query. 4. If "Yes" then type the new text and press <Esc>. Answer the End Points Query and mark a starting point if desired.. 5. If "No" then go into Point mode and mark the block that is to be linked to. 6. Press <Esc>. The other aspect of Reference links and their creation that is not covered
here is graphics. For a detailed discussion of graphics please see chapter 10. Jump To Chapter 10. Limitations 8 More Restrictions Although linking in Black Magic appears completely freeform, without any
restrictions, it is not. There are certain restrictions that if not followed
will cause errors in ,Black Magic or in ' your file. These restrictions are
as follows: ∙ There can be no links from within a note window. ∙ When creating a Reference link you cannot use point mode to
point to text in a Note window. ∙ Graphics cannot be the material for a Replacement link. ∙ Links must be made one at a time. Each link must be finalized
before another link can be made. ∙ Don't Cut, Copy, and Paste Links. It is possible to do this, but
it gives erratic results that may lead to ' damaged files, so
it is not advised. Infinitely? Actually "infinitely" is more poetic license than technical fact but for practical purposes, its close. Black Magic limits you to 32,767 reference link levels of hierarchy. This isn't infinite, but it probably could not be reached due to RAM limitations. One way though to create very large hypertext documents i.e. larger than available RAM is to utilize the technique of File Links. "Structure" is used here to refer to the
way that the links are put together and
how they are related to each other. When you create a Reference Link going
to new text, that "new text" may be
either typed in, imported as an ascii
file, or a combination of the two. Linking to already existing text is done by using what is
called Point Mode. In Point Mode, you simply go to the text that you want to
link to, mark its beginning as a block and press <Esc>. The link will then be made. i.e. text that was previously typed Text that you need to type/import Pressing "Y" will link the entire block of text to the original reference link making the cursor simply jump to the beginning of the newly typed text. Pressing "N" allows you to link the reader to a specific spot in the newly typed text. The benefit to this is that if there is a specific word or phrase among the new text that has been typed that should stand out, this will allow it to; by bringing the cursor directly to it. After answering "N" to the prompt, it is necessary to define
the area that you wish to be directly pointed to. This is
done by moving the cursor to the area that the cursor should
be brought to pressing <Shift> <ArrowKey> to highlight it.
Once the highlighting is done, pressing <Esc> will complete
the link, returning you to the links originator. First of all, the text that was designated as hypertext is surrounded by colored symbols. This is the normal way that hypertext is indicated. When the cursor is moved between the symbols, and <F1> is pressed the user is taken to the text that was designated as hypertext, with the cursor landing on the block of text that was highlighted. Chapter 10 covers the use of graphics as
Link Originators and Link Ends. 0DOS Links The Dos link is used to exit Black Magic, perform an operation (or several operations) at the DOS level and then re-enter Black Magic exactly where you left off. The uses for this new link type are near endless. Some examples include the ability to create custom DOS Shells using Hypertext, the ability to integrate hypertext with the power of a full expert system, and the ability to integrate hypertext into systems of your own design. Using DOS Links Explanation OF DOS Link Editor Mode Reader Mode Creating A DOS Link DOS Links are created in the same fashion as any other link type. First a Block of text is marked, then the DOS Link Key (<L><Ctrl> <F3><F3>) is pressed. Now a note link type window will come up on screen for the entry of the DOS batch file. Once the batch file is entered, the following line must be added to the end of it. Statement Comment @RESTART (Reloads Black Magic with the Correct file) This last line must be present in the batch file or Black Magic will not properly return and reload the correct file. Comments When a DOS link is executed from within the MAGIC.EXE program itself, you may feel that it is slow in operation. This is primarily due to the fact that MAGIC has to first save the current file to disk (to save any changes) and then exit to DOS and execute the Batch file. When a DOS link is activated using the reader (MAGREAD.EXE) then the performance is substantially improved because the file does not have to be saved. Examples The following example will demonstrate how to create a DOS link that leaves Black Magic, loads Microsoft Excel and a spreadsheet file, allows you to do some work and then return to Black Magic automatically. The file that we are working with is called EXCEL.MAG. It is a hypertext document that talks about the advantages of using Microsoft Excel over Lotus 123. At the first occurrence of the word Excel (First node, Top Center), we are going to mark it as a block. Once it is marked as a block, press <L><Ctrl ><F3> <F3>. A DOS link window will come up on screen to enter the batch file. Below is the complete batch file to be entered. CD\WINDOWS EXCEL LOTUS.XLS @Restart The above batch file will exit Black Magic when the link is activated, change the current directory to c:\windows and then load excel and the file LOTUS.XLS. When you exit excel, the Batch file will resume execution and change the current directory to C:\MAGIC and then load magic and the file that you were working on.Note - the above example file can be downloaded from the Hyperboard! (203-366-5698) as EXCEL.MAG. Created by pressing <Ctrl> <F3> when a
block is marked. Using DOS Links First of all, Black Magic's DOS link is not simply shelling to DOS, running a program, and then returning to Black Magic. Instead it is actually exiting Black Magic to DOS, running a custom Batch File which performs the desired task, reloading Black Magic and also the document that you were using when you exited. This rather indirect method was chosen because of memory constraints. Once both Black Magic and a hypertext document are loaded, there is often not enough memory to shell to DOS and accomplish anything useful. By unloading Black Magic itself, there is always enough memory to link from Black Magic to large memory hungry programs like expert systems. When Black Magic is in editor mode, activating a DOS Link
by pressing <F1> or using the mouse, first brings the window
up on screen with the contents of the Batch file in it.
This allows you to edit the batch file. Then if you still
wish to activate the DOS Link, pressing <F1> a second time
inside the window activates the link. In reader mode or when you are using MAGREAD to read a
hypertext document, the DOS Link acts differently. Here
because nothing can be edited, activating the link simply
exits Black Magic and executes the batch file. It happens
directly without any pauses and is not an abortable process. Explanation of DOS Links DOS links are simply a command to leave Black Magic and execute a predefined Batch File. Then after the Batch file is run, it can reload Black Magic and the document file that you were working with. The batch file that defines every DOS link is written when the DOS link is created. After pressing <Ctrl> <F4> to indicate a DOS link, a window comes up on screen for the entry of the batch file. The user can now write the batch file that defines the operation of the DOS link. Once the Batch file is complete, pressing <Esc> finishes the link. When the link is activated, Black Magic then writes the contents of the window to a DOS batch file that is saved to the document directory when the link is activated. When the DOS link is activated, it can function in two different ways, Editor (File) Mode or Reader Mode. File Links File Links, a way to join two or more .MAG files together, are now substantially easier to use. A file link can now be created through the use of the menu systems as opposed to the previous method. The key item to note in creating file links is that both files must previously have been created. A file link then acts to join these two existing files together. Creating A File Link Comments Creating A File Link To create a file link, first mark the link originator as a block (use <Shift> <ArrowKey>). Next, press <F10> I E F. This signifies that a reference link is to be created to a file. Black Magic will now prompt you for the file to link to. After the file name is entered and <Enter> is pressed, Black Magic will save the current file to disk and then load the requested file. With the new file up on screen, goto the section of the document that you wish to link to and mark it as a block. After it is marked, press <Esc>. Black Magic will then reload the original file after <Esc> is pressed. Comments One thing to note about file links is that their performance is dependent on the size of the file that they have to load. The implication here is that you would be better off structuring your documents to be file linked together as many smaller documents rather than one monolithic document. A second thing to note is that file links will always perform better running under the reader (MAGREAD.EXE) than under the writer (MAGIC.EXE). The reason for this is that under the writer, the file must always be saved before the linked file can be loaded. Under the reader there is not this restriction. Hypertext Reports
Editing Reports Replacement Links Graphics Single File Link Comments New to version 1.4 is the reporting function. This feature allows you to create reports for each link that are written to an ascii file when the link is activated. This feature is particularly useful for passing parameters between Black Magic and other programs. Another use for this is tracking the sections of a document that a user has read. Using the Report Function Reports can be defined for any existing link type: Reference, Note, DOS and Replacement . Also, reports can be defined for any link type originating out of a graphic. To create a report for a link, move the cursor between the two link markers
(the 2 link originator) for the link you wish to add a report to. Next press
the Report Key (<Ctrl> <F1>) or issue the Report command from the Link menu.
A dialog box similar to those used for the entry of DOS links will appear on
screen: The first line to enter in the report must be the following: @FILENAME.EXT The '@' indicates to Black Magic that what follows is the filename that the report is to be written to. The 'FILENAME' should be replaced with the name of the file that you wish the report written to. The 'EXT' is any three character extension that you wish, but it is not required. Note: without the first line indicated above, Black Magic will disregard the report and NOT generate a file because it will not recognize the filename to write to. The next step is to enter the rest of the report. This is simply the text of the report that should be written to the ascii file. It can be of any length and does not require any special characters to end it. After the report is finished, simply press <Esc> and the report is completed. Now whenever the link is activated, the report will be written to the filename defined in the first line of the report.
Editing and Deleting Reports To edit a report, simply move the cursor between the link markers of the link that has the report you wish to edit and press the report key (<Ctrl> <F1>) or give the Report command from the Link menu. The existing report will come up on screen and then can be edited as can any other piece of text. To delete a report, simply call up the report as described above and delete all the text that is there. Replacement Links Replacement links in Black Magic can be viewed as being "double sided" or circular in that there is no actual clearly defined originating state to a replacement link like there is with a Reference or Note link. A benefit to this is that both "sides" of the replacement link can have different reports assigned to them. Two such reports are defined below: @@SIDE1.TXT This came from the first side of the link Hi ! @@SIDE2.TXT This came from the second side of the link Bye ! When the replacement link was first activated, the file SIDE1.TXT would be created and the report written. The second time the link was activated, the file SIDE2.TXT would be created and the original side of the link would displayed on screen. Graphics and the Report Function Graphic links (links originating from a graphic) can also have reports defined for them. To add a report to a graphic link, first move the cursor onto the link as if you were going to activate it. Next press the Report key (<Ctrl> <F1>) and enter the report as described above. When you are finished entering the report, simply press <Esc> and the report will be finished. Writing Multiple Reports to a Single File One of the problems with report links and large hypertext documents is that if there are a large number of reports defined, many report files may be generated taking up valuable disk space. The solution to this is to generate reports that are appended to existing reports already written to files. Note: if there is not an existing report on disk then the report would be written to a new file. In order to append reports to existing files, two '@' signs must precede the filename on the first line. This is depicted below: @@FILENAME.TXT This was the First Link in the document The above report would be appended to the file FILENAME.TXT. Report Function and Commenting Reporting Function as Comment Function An additional use for the reporting function is that it can be used as a method of inserting non-displaying (to the reader) comments for yourself or other developers. This allows you to add information to the document only pertinent to the developer such as comments about unfinished work, link structure and so on. To add a comment to a link, simply press the Report key and do not enter a filename on the first line or the @ symbol. Then whatever comments that you wish to enter can be typed. After you are done, simply press <Esc> and the comment is finished. .Replacement Link ! Limitations ! Creation ! Summary The Replacement Link allows a specified block of text to be "swapped" or "replaced" by a second block of text. " #Uses Replacement Links are represented by a pair of pink squares surrounding the 6 Link Originator. $Warning!!! Creation Creating a replacement link is done in the same fashion as any other link. The first step is to define the text that is to be replaced by marking it as a block with <Shift <ArrowKey>. After the block is defined (shown by highlighting), pressing <Alt> <F3> will signal that this is to be a replacement link. This will call up a window on screen for entering replacement text. Text can be entered into this window in 3 ways: Simply Typing It. Pasting It In From the Block Buffer Importing It From An Ascii File After the replacement link text is entered, pressing <Esc> will back out of the link and return the original text to its position. %Visual Changes &Functional Changes !Limitations Additional Limitations The material for a replacement link can be anything, even other links. One limitation on replacement links is that there cannot not be be a graphic image within a replacement link. 9 How To Use a Replacement Link and Graphics However there could well be a reference link within the replacement link that had a graphic as its link end. Or alternatively there could be a Note link within the replacement text that contained graphics as its link end. The second limitation is that there cannot be a Replacement Link nested inside a Replacement Link. It can be done, but the only result from it is a ' damaged file. "Replacement Link Summary Creating a Replacement Link is done in the following manner. 1. Mark the block of text that is to be a link. 2. Press <Alt> <F3>. 3. Enter the Replacement Link text. 4. Press <Esc> and resume writing. The uses for a replacement link are many and varied. For example, when using reference links in a document, there is always the possibility that an inexperienced reader (or writer) could get lost in the process of tracking them. With this in mind, the replacement link can be used to substitute short bits of information that would otherwise be accessed by means of a reference link. One example of what can be done with a replacement link, would be to replace the phrase "Cars are driven by engines." with a description of what cars are and how an engine functions. Another example of what can be done with replacement Links is the kind of Text Expansion that you are seeing now. By my replacing "Uses" with these paragraphs explaining them. This approach of information expansion allows information to be available to the user on demand as opposed to forcing large quantities of information down a user's throat all at once. This type of interactivity is one of the key features or characteristics of hypertext. Warning !!! The Replacement link has one major difference between it and the other types of links. Note and Reference links both use <F1> to traverse a link forwards and <Esc> to return (traverse backwards) from a link. However the Replacement link is set up with a "loop" type
structure. To access the replacement text, press <F1> and
then the original text is accessed by pressing <F1> again.
Pressing <Esc> on a replacement link has no effect, on it as
there is no "backwards" in a Replacement Link. Immediately noticeable are the colored symbols surrounding the text that you
marked as the link originator. Moving the cursor between the symbols
and pressing <F1> will activate the link
and swap its replacement between the
markers. 9Damaged Files Certain combinations of link nesting can result in the
program becoming confused. The character Ω will be used to
denote links in the simulated line below. The first link
is shown in all Capitals, while the second link is shown in
all lower case letters. The word "links" belongs to both
links and it is therefore capitalized. ΩREPLACEMENT ΩLinksΩ can have any text in them.Ω It is unclear above which markers go to which links. The
same thing going through your head, happens inside the
computer. It gets confused by the above type of link
structure. If you were to try to activate the link on the
word "Links", the computer could not know which link to
activate. It is therefore a good idea to nest a link entirely within
a replacement link. The Replacement link is the only link
which can have another link originator nested inside it,
and a replacement link can not be nested inside another
replacement link. # $ -Note Link ( Window Commands ( Summary The note link is the simplest type of link, and consequently tends to form the
basis for learning hypertext. Note Links pop up a window on screen that
contains a "note" pertaining to the text on screen linked to the note. The
note can consist of either text or graphics. Creation To create a note link, it is first necessary to )define the block of text
that is to be hypertext; the 4Link Originator. This block can be a single
character, a word, a line, even a paragraph or page. Defining As Hypertext Once the block is defined, it is necessary to indicate that the block is a
note link by pressing <Shift> <F3>. This calls up a rectangular window on
screen in the upper left hand corner and moves the cursor into it. The contents of the note are entered into this window. The note's contents can be entered in three different ways: Typing Text Importing Text Importing A Graphic Pasting Text Also a combination of Typing text and importing Text files could be used. After the contents of the Note are entered, pressing <Esc> will complete the
Link; returning you to the 5Link Originator. Although the block is no longer
defined by highlighting, it is now surrounded by two yellow symbols shaped
like diamonds, indicating it is a Note Link. Now if you move the cursor between the two diamonds. and press <F1> it will
activate the link and display the contents of the Note Window. %Window Commands There are two commands that pertain specifically to Note windows: *Window Size + 6Window Name Both of these commands are only usable when a Note Link has been activated and
the corresponding Note Window is on screen. &Note Link Summary Creating a Note Link is done in the following manner. 1. Mark the block of text that is to be a link. 2. Press <Shift> <F3>. 3. Type the Note Link. 4. Press <Esc> and resume writing. The other aspect of Note links and their creation that is not covered here is graphics. For a detailed discussion of graphics please see chapter 10. Block Definition Defining the block, is done with <Shift> <ArrowKey>. By pressing <Shift> <ArrowKey>, you will notice that the block of text is highlighted in another color. This is to indicate what makes up the block of text. Window Size is activated by pressing
<Shift> <F2> or choosing it from the
window menu. This will then prompt you for the new
window height and width. Window Name is activated by pressing <Ctrl> N or by
choosing it from the menu. This then prompts you for a
twenty character name for the window to be displayed at the
top of the window. NOTE: Named Windows and Graphics. In order to display a graphic in a named window, the window
must be named before the graphic is imported. The result of this woudl be a lockup or
